feat: add sentry span list and sentry span view commands#393
feat: add sentry span list and sentry span view commands#393
sentry span list and sentry span view commands#393Conversation
Move computeSpanDurationMs from human.ts to trace.ts and add shared utilities for the upcoming span commands: flattenSpanTree, findSpanById, parseSpanQuery, applySpanFilter, writeSpanTable, and formatSpanDetails. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add span as a first-class command group for AI-agent trace debugging. - span list: flatten and filter spans in a trace with -q "op:db duration:>100ms", --sort time|duration, --limit - span view: drill into specific spans by ID with --trace, shows metadata, ancestor chain, and child tree - spans: plural alias routes to span list Closes #391 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Semver Impact of This PR🟡 Minor (new features) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨Init
Issue List
Other
Bug Fixes 🐛Dsn
Init
Other
Documentation 📚
Internal Changes 🔧Init
Tests
Other
Other
🤖 This preview updates automatically when you update the PR. |
Codecov Results 📊✅ 111 passed | Total: 111 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 91.61%. Project has 1101 uncovered lines. Files with missing lines (3)
Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
- Coverage 95.10% 95.01% -0.09%
==========================================
Files 159 162 +3
Lines 21513 22043 +530
Branches 0 0 —
==========================================
+ Hits 20459 20942 +483
- Misses 1054 1101 +47
- Partials 0 0 —Generated by Codecov Action |
The UUID dash-stripping is already handled silently by validateHexId. Remove the validateAndWarn wrappers, mergeWarnings helper, and all related warning assertions from tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Duration filter `>` vs `>=` was wrong — `duration:>100ms` included 100ms instead of excluding it. Added exclusive/inclusive tracking to SpanFilter and extracted duration comparison helpers. Also made `span view --json` always return an array for consistent output shape. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ce view Use the server-side spans search endpoint (dataset=spans) for `span list` instead of fetching the full trace tree and filtering client-side. Add `translateSpanQuery` to rewrite CLI shorthand keys (op→span.op, duration→span.duration) for the API. Also fix trace view showing `undefined` for span IDs — the trace detail API returns `event_id` instead of `span_id`, so normalize in `getDetailedTrace`. Append span IDs (dimmed) to each tree line. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move listSpans from monolithic api-client.ts into api/traces.ts module to align with main's refactored re-export structure. Keep span_id display without null coalescing (TraceSpan.span_id is required). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ring
Migrate span list/view from imperative output to auto-rendered OutputConfig
pattern, and fix plain-mode ANSI leaks in span tree/ancestor formatting.
**Output system migration (span/list.ts, span/view.ts):**
- Replace `output: "json"` shorthand with `output: { json: true, human: fn, jsonTransform: fn }`
- Extract human formatters (formatSpanListHuman, formatSpanViewHuman) that
return strings instead of writing to stdout directly
- Extract JSON transforms (jsonTransformSpanList, jsonTransformSpanView) for
the { data: [...], hasMore } envelope and --fields filtering
- Return `{ data, hint }` from func() so the wrapper handles rendering
- Remove manual `if (flags.json)` branching and direct stdout writes
**Markdown rendering fixes (trace.ts, human.ts):**
- formatAncestorChain: replace raw `muted()` (chalk ANSI) with
`colorTag("muted", ...)` + `renderMarkdown()` so output respects
NO_COLOR/isPlainOutput/non-TTY
- formatSimpleSpanTree/formatSpanSimple: replace `muted()` with
`plainSafeMuted()` that checks `isPlainOutput()` before applying ANSI
- Span list header now renders via `renderMarkdown()` for proper styling
**Formatter exports (trace.ts):**
- Export SPAN_TABLE_COLUMNS for use by span/list formatter
- Add formatSpanTable() return-based wrapper around formatTable()
After merging main, command.ts uses async generators + CommandOutput class:
- Remove 'json: true' from OutputConfig (no longer needed on main)
- Change async func → async *func (generator)
- Replace return { data, hint } → yield new CommandOutput(data) + return { hint }
- Import CommandOutput from formatters/output.js
- Remove dead code: flattenSpanTree (unused, superseded by EAP API) - Remove dead code: writeSpanTable (superseded by formatSpanTable) - Fix case-insensitive span ID matching in findSpanById — lowercase the API-returned span_id before comparing with user-lowercased input - Fix JSON duration consistency: use computeSpanDurationMs() in buildJsonResults instead of raw r.span.duration, matching the human output path's timestamp-arithmetic fallback
|
Addressed all Cursor BugBot feedback in f7198cc:
|
The orgSlugArb and projectSlugArb generators could produce strings starting with 'xn--' (punycode-encoded IDN labels). When used as a subdomain (e.g. 'xn--0a.sentry.io'), the URL constructor silently decodes the punycode, collapsing the hostname to 'sentry.io' and dropping the org. This caused flaky failures in the buildTraceUrl → parseSentryUrl round-trip test. Fix: filter out xn-- prefixed slugs since real Sentry org/project slugs are never punycode-encoded.
- Restore null fallback for span_id in formatSpanSimple: span.span_id ?? '' (defensive against runtime undefined from normalizeTraceSpan edge cases) - Unexport SPAN_TABLE_COLUMNS — only used internally by formatSpanTable, no external consumers
Use optional chaining (span.span_id?.toLowerCase()) to avoid crash when a span from the API has neither span_id nor event_id.
UX improvement: Replace --trace flag with positional argument to match the standardized [<org>/<project>/]<id> pattern used by span list, trace view, and event view. Before: sentry span view <span-id> --trace <trace-id> After: sentry span view [<org>/<project>/]<trace-id> <span-id> This is consistent with span list which already uses: sentry span list [<org>/<project>/]<trace-id> SKILL.md: Update placeholder text from generic '<args...>' to descriptive '<org/project/trace-id...>' and '<trace-id/span-id...>'. Tests: Add comprehensive tests for both span commands: - span/list: parsePositionalArgs, parseSort, and func body tests (API calls, query translation, org/project resolution) → 86.71% coverage - span/view: validateSpanId, parsePositionalArgs, and func body tests (span lookup, JSON output, multi-span, child tree) → 86.89% coverage - formatters/trace: findSpanById (case-insensitive, undefined span_id), computeSpanDurationMs, spanListItemToFlatSpan
The hint in span list still referenced the removed --trace flag. Updated to: 'sentry span view <trace-id> <span-id>'
The <project>/<trace-id> format doesn't work because parseSlashSeparatedArg treats a single-slash input as org/project (missing ID), not project/trace-id. Unlike span list or trace view, span view can't fall back to two separate args since the second positional is always a span ID.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Summary
Adds
sentry span listandsentry span viewso AI agents can filter/drill-into individual spans within a trace, instead of dealing with the full nested tree dump fromsentry trace view --json.Workflow this enables:
Changes
Shared utilities (
src/lib/formatters/trace.ts):computeSpanDurationMsfromhuman.tsintotrace.tsfor reuseflattenSpanTree— converts nested span tree to flat array with depth/child_countfindSpanById— searches tree returning span + ancestor chainparseSpanQuery/applySpanFilter— parse and apply-q "op:db duration:>100ms project:backend"filterswriteSpanTable/formatSpanDetails— table and detail formatterssentry span list(src/commands/span/list.ts):[<org>/<project>] <trace-id>(same pattern astrace view)--query/-q: filter by op, project, description, duration thresholds--sort:time(default, depth-first order) orduration(slowest first)--limit/-n: cap output (default 25, max 1000)totalSpansandmatchedSpansin envelopesentry span view(src/commands/span/view.ts):[<org>/<project>] <span-id> [<span-id>...](multi-ID likelog view)--trace/-t: required trace ID--spans: child tree depth (default 3)Route wiring (
src/app.ts):sentry span {list, view}routesentry spansplural alias →span listTest Plan
bun run typecheckpassesbun run lintpasses (0 errors)bun run test:unit— all 3370 passing tests still pass (43 pre-existing failures unrelated)sentry span list <trace-id> --json --limit 5sentry span list <trace-id> -q "op:db" --sort durationsentry span view <span-id> --trace <trace-id> --jsonsentry span view <span-id> <span-id> --trace <trace-id>Closes #391